//  IModel.hpp
//  PureMVC_C++
//
//  PureMVC Port to C++ by Tang Khai Phuong <phuong.tang@puremvc.org>
//  PureMVC - Copyright(c) 2006-2011 Futurescale, Inc., Some rights reserved.
//  Your reuse is governed by the Creative Commons Attribution 3.0 License
//
//  中文注释：
//  IModel接口定义了PureMVC框架中的模型组件。
//  它负责管理应用程序的数据模型，通过Proxy对象来维护数据。
//  模型提供了注册、检索和移除Proxy实例的方法，并维护Proxy实例的缓存。
//

#if !defined(__PUREMVC_INTERFACES_IMODEL_HPP__)
#define __PUREMVC_INTERFACES_IMODEL_HPP__

// STL include
#include <string>
// PureMVC include
#if !defined(__PUREMVC_HPP__)
#define __PUREMVC_INCLUDE__
#include "../PureMVC.hpp"
#endif /* __PUREMVC_HPP__ */

#include "IProxy.hpp"
#include "IAggregate.hpp"

namespace PureMVC
{
    namespace Interfaces
    {
        /**
             * PureMVC模型的接口定义
             * The interface definition for a PureMVC Model.
             *
             * <P>
             * 在PureMVC中，<code>IModel</code>实现者通过名称查找提供对<code>IProxy</code>对象的访问。
             * In PureMVC, <code>IModel</code> implementors provide
             * access to <code>IProxy</code> objects by named lookup. </P>
             *
             * <P>
             * <code>IModel</code>承担以下责任：
             * An <code>IModel</code> assumes these responsibilities:</P>
             *
             * <UL>
             * <LI>维护<code>IProxy</code>实例的缓存</LI>
             * <LI>提供注册、检索和移除<code>IProxy</code>实例的方法</LI>
             * <LI>Maintain a cache of <code>IProxy</code> instances</LI>
             * <LI>Provide methods for registering, retrieving, and removing <code>IProxy</code> instances</LI>
             * </UL>
             *
             * @see Interfaces/IIterator.hpp PureMVC::Interfaces::IIterator
             * @see Interfaces/IAggregate.hpp PureMVC::Interfaces::IAggregate
             */
            struct PUREMVC_API IModel
        {
#if defined(PUREMVC_USES_TR1)
            typedef std::unique_ptr<IAggregate<std::string> > ProxyNames;
#else
            typedef std::auto_ptr<IAggregate<std::string> > ProxyNames;
#endif

            /**
                 * 向<code>Model</code>注册一个<code>IProxy</code>实例
                 * Register an <code>IProxy</code> instance with the <code>Model</code>.
                 *
                 * @param proxy 要由<code>Model</code>持有的对象引用
                 * @param proxy an object reference to be held by the <code>Model</code>.
                 */
                virtual void registerProxy(IProxy* proxy) = 0;

            /**
                 * 从模型中检索<code>IProxy</code>实例（常量版本）
                 * Retrieve an <code>IProxy</code> instance from the Model.
                 *
                 * @param proxy_name 代理名称
                 * @param proxy_name
                 * @return 先前用给定<code>proxy_name</code>注册的<code>IProxy</code>实例
                 * @return the <code>IProxy</code> instance previously registered with the given <code>proxy_name</code>.
                 */
                virtual IProxy const& retrieveProxy(std::string const& proxy_name) const = 0;

            /**
                 * 从模型中检索<code>IProxy</code>实例（非常量版本）
                 * Retrieve an <code>IProxy</code> instance from the Model.
                 *
                 * @param proxy_name 代理名称
                 * @param proxy_name
                 * @return 先前用给定<code>proxy_name</code>注册的<code>IProxy</code>实例
                 * @return the <code>IProxy</code> instance previously registered with the given <code>proxy_name</code>.
                 */
                virtual IProxy& retrieveProxy(std::string const& proxy_name) = 0;

            /**
                 * 从模型中移除<code>IProxy</code>实例
                 * Remove an <code>IProxy</code> instance from the Model.
                 *
                 * @param proxy_name 要移除的<code>IProxy</code>实例的名称
                 * @param proxy_name name of the <code>IProxy</code> instance to be removed.
                 * @return 从<code>Model</code>中移除的<code>IProxy</code>
                 * @return the <code>IProxy</code> that was removed from the <code>Model</code>
                 */
                virtual IProxy* removeProxy(std::string const& proxy_name) = 0;

            /**
                 * 检查是否注册了代理
                 * Check if a Proxy is registered
                 *
                 * @param proxy_name 代理名称
                 * @param proxy_name
                 * @return 当前是否用给定的<code>proxy_name</code>注册了代理
                 * @return whether a Proxy is currently registered with the given <code>proxy_name</code>.
                 */
                virtual bool hasProxy(std::string const& proxy_name) const = 0;

            /**
                 * 获取所有代理的名称
                 * Fetch all names of proxy
                 *
                 * @return <code>proxy_name</code>的聚合容器
                 * @return the aggregate container of <code>proxy_name</code>.
                 */
                virtual ProxyNames listProxyNames(void) const = 0;

            /**
                 * 虚析构函数
                 * Virtual destructor.
                 */
                virtual ~IModel(void);
        };
    }
}

#endif /* __PUREMVC_INTERFACES_IMODEL_HPP__ */
